Mac Magazin/MacEasy 21/Mac Magazin and MacEasy Magazine CD - Issue 21.iso/Wissenschaft & Technik/yorick_docs folder/yorick-mac-Intro

Text File | 1996-02-29 | 15KB | 284 lines

Introduction
------------
Yorick is a tool for analyzing numerical data. It has an interpreter
that uses a C-like language and can operate on entire arrays without
any need for do loops over the array indices. Yorick has a file I/O
package with the ability to conveniently read text files with
columns of numbers. The file I/O package can easily be trained to
read a wide variety of binary and text files, if the formatting
rules for the file are known. Yorick has a 2D graphics package that
includes polylines, contour plots, cell arrays, and filled mesh
plots. The new 3D graphics package provides surface plots, slicing
planes, and iso-surfaces.

Instructions to the unix version of yorick are typed in a command
window, and yorick writes responses to the command window and draws
plots in one or more graphics windows. The user interface for yorick
is text input oriented by design - the easiest way to specify
transformations to apply to data is usually some equation-like form.
The Macintosh version has a somewhat more user  friendly interface,
but it is still controlled via text commands.

Gist is a program that displays frames in binary CGM files written by
yorick and other applications (e.g. ATC GKS, IDL). gist is
particularly useful for making PICT files from a CGM file written by
a Unix version of yorick.

The performance of yorick on the Macintosh is good in comparison to
competing analysis tools. The PowerMac version delivers performance
comparable to a current low end Sun workstation for computation
intensive tasks. The graphics performance on my PowerMac 7100 is
about like a high end x-terminal, which is less than a low end
workstation. The graphics performance should be better on a PCI
based Mac (I have not had a chance to test this).

The Macintosh version of Yorick was created by Steve Langer
([e-mail]) from the Unix version written by Dave Munro.
This file contains some short notes about the Macintosh version, but
it is in no way an introduction to yorick. To learn how to use yorick
you will have to examine the files in the doc directory and run
yorick. The first thing you should probably do is to print the "cheat
sheets". These PostScript files summarize the yorick language and
commands. If you have a copy of Adobe's ATM, you can print
PostScript files using the SendPS utility. Once you have yorick
running, one of the nice features is the help command. If you know
that "plg" is the command to make a y versus x plot, but don't
remember the arguments, type "help,plg". By paying attention to the
"see also" functions, you can find out a great deal without needing
to look at the manual.


Installation
------------
Yorick is distributed in several self-extracting archive files. There
is a version that runs on any 68020, 68030, or 68040 Mac with a
floating point chip (FPU), another version that runs on 68020, 68030,
or 68040 Macs without an FPU (e.g. 68040LC), and a Power Mac version.
There is also a PowerMac version of gist and a 68000 version that
does not require an FPU. Each version of gist and yorick checks for
the Mac hardware and software it requires and aborts if it is not
found (it is possible that detection of old 68000 Macs does not
work).

The include, startup, and gist directories must be in the same folder
as the yorick application (they are organized this way in the files
we distribute). If you frequently need to include files from
specific directories, add the directory to the yorick search path in
your custom.i file (located in the yorick/include folder).

If you have MacBinary capability in your ftp program, download the
"sea" file. If you are using a unix-like ftp, download the "hqx" file
and use a program like UnStuffIt to decode the BinHex file. Once you
have the "sea" file, double-click on it and it will automatically
split itself apart into the constituent files.

NOTE: Yorick ships with a preferred memory allocation of 3-5 MB,
depending on the target procesor. Most simple calculations (like
operations on 1D arrays) should run just fine in the minimum 2 MB. The
larger size is intended to permit reasonable 2D computations. You can
increase the memory allocation if you are working on large 2D or 3D
datasets.


Macintosh Version
-----------------
The Macintosh version of yorick is very similar to the Unix version,
and almost all of the yorick documentation should apply. The main
difference between the Mac and unix versions of yorick is in the user
interface. The unix version runs in a terminal window while the mac
version includes a built in command window with command re-issue
capabilities and text editor windows that can be used to prepare
yorick programs. Another difference is that the Mac version can save
any graphics window to a PICT file (as well as yorick's native CGM
and Postscript formats).

The macyorick command window is closer to being a text editor than a
dumb terminal window. The main thing to know about the command window
is that when you press the return key, everything to the left of the
cursor in the current line is passed to yorick as a command. If there
is any selected text when the return key is pressed, the selected
text is passed to yorick as a command. This last feature can be used
to send several lines at a time to yorick. All yorick output will be
sent to the command window.

When you type a command or call the read function to get keyboard
input, macyorick first removes anything it recognizes as a prompt
string from the start of the line and then passes the rest of the
line. This usually works well, but it can be fooled if you do
something like declaring a variable called cont and then try to
evaluate the following expression: cont> 3 mac yorick will remove the
"cont> " before processing the line. This is a consequence of prompt
removal, not a bug. Don't use  prompt strings at the start of an
input line ("read> ", "do> ", "cont> "). Don't set the prompt string
for the read function to the name of one of your variables.

Yorick has simple text editor windows that can be used for examining
ascii data files or preparing yorick input decks. An editor is
created using the "New Editor" command in the file menu. Text editor
windows have an "execute" button that causes the contents fo the
editor to be read as if yorick had been given an include command. If
you are creating a new file, the file must be saved before the
execute button will work.

When yorick detects an error while processing the commands in a file
(even nested include files), it will open the offending file in a
text editor and place the cursor on the bad input line (this behavior
can be disabled).

If you double-click in the Finder on a file of type 'TEXT' with a
creator "York', yorick will be launched, it will set it's working
directory to the directory where the file is located, and it will
then open the file into a text editor window. To run the program,
just click the execute button.

The Macintosh version also supports the use of "command-period" to
abort long running yorick calculations. Yorick only checks for
command-period between interpreted commands and while writing to the
command window. If you have started a matrix solve that will take an
hour to complete, using command-period will not help, because it will
not be checked until the matrix solve completes. This feature is
turned on by default, but may be disabled in the preferences dialog
in the edit menu.

Yorick and gist both have a preferences dialog that is reached from
the Edit menu. Graphics preferences in gist apply to the single
graphics window. In yorick, graphics preferences can be set for
future graphics windows from the edit menu or for an existing window
using the preferences button in the window. gist has an option to
select either yorick-style CGM files or CGM files made by ATC GKS. If
you don't know what this means, stick with yorick CGM files.

Graphics
--------
The Macintosh version of yorick implements the full gist graphics
package. Each graphics window has a button that saves the current
plot as a PICT file, a button to redraw the window, and a button to
set the preferences flags for graphics. The PICT file can be set up
either to produce a high quality image when printed or in a form that
will make it easier to edit the PICT file in Canvas, MacDraw, etc.

macyorick includes the new 3D graphics functions found in the unix
version. These include surface plots, slicing planes, and
isosurfaces. These functions use a drawing algorithm that is fast but
may generate incorrect results for polygons that extend a long way
into the screen. If you are plotting using a reasonably smooth grid,
you should not see any problems. The new 3D package is easy to use,
for a 3D package. The problem with 3D graphics is that you need to
give depth cues on a 2D screen, and generating good depth cues is not
always easy. Yorick includes functions to set the position of the
light(s) illuminating the surfaces and to rotate objects in 3D.  Look
at the examples in demo5.i and experiment with your own  favorite
plots. This package will continue to evolve as we get more
experience with 3D graphics. If you have any comments, please contact
us so we can consider your suggestions.

There is another problem that occurs with color plots when you have
an 8 bit deep screen. Yorick loads a color table of roughly 240
colors and uses those in plotting to the screen. Yorick allows you to
pick from a number of pre-defined color tables, or to create your
own. This allows you to produce striking cell arrays or filled
meshes on an 8 bit screen. The problem is that if you save the plot
in a PICT file, any Mac program that loads the PICT file is unlikely
to be using the same color table as yorick used in creating the
image. The Mac will do the best job of displaying the image that it
can given the current color table, but a lot of "banding" may show up
in the image. The only way to fix this, with an 8 bit screen, is to
load the same color table into the other Mac program as was used by
yorick (non-trivial). HOWEVER, all of the color information is still
present in the file, so the colors will show up properly on a color
printer. This problem should not be noticeable on a 16 or 24 bit
"true color" screen.

macyorick supports yorick's animated graphics mode. In the normal
graphics mode, everything appears on the screen as it is drawn. In
animation mode, the whole plot is drawn in an offscreen pixmap and
then copied to the screen all at one time. The result is that in
animation mode, the transition between successive pictures is smooth.
Animation mode is particularly useful in viewing the results of a
time dependent simulation. The simulation might have saved its
results in a file, or the simulation might actually be run directly
by yorick (see demo2.i for an example). Run demo3.i for an
introduction to animation mode.

Yorick can write plots to binary CGM files. The CGM file was
originally developed for use on mainframe computers, and the standard
is showing its age in some respects. One of the key problems is that
there is no defined way to specify the exact font you desire in a CGM
file. The result is that the program that wrote the CGM file can
usually display it exactly, but other programs (e.g. Canvas) only
produce an approximate rendition. My suggestion is that you use CGM
files as places to store a group of related images (the CGM file
could even be written on a Unix workstation). When you need to use an
image in another Mac program, load the CGM file into the Macintosh
version of gist (a CGM file browser) and save the desired frame as a
PICT file.


Known Bugs and Missing Features
-------------------------------
0) Yorick has been heavily tested on Unix workstations for a couple
of years now and has been available on the Macintosh since late in
1994. It has been used for a wide variety of production calculations,
but we still find several bugs a year.  The bugs don't prevent us
from using yorick, and  are about what should be expected from a code
of this complexity.  The Mac version of yorick is roughly as reliable
as the unix version.  The core code is the same as for the unix
version, so  any Mac specific bugs are most likely to be in the
graphics package or the user interface. As a new yorick user,  your
problems are most likely to stem from giving yorick the wrong
command, or possibly from asking yorick to do something that will
take forever. Look at the examples and start with simple problems,
and things should go pretty smoothly.

1) If your CGM files wind up in pure black and white, try using the
"dump=1" option on the hcp_file command. The default behavior is to
dump a gray scale file on the theory that most printers are black and
white. There is some reason to think that the default should be to
dump the color table, but for now you need to explicitly dump it.

 2) PICT files should have proper colors, but programs like MacDraw
and Canvas will often fail to display the full range of colors on 8
bit screens. This happens because they are using a color table that
does not match the one originally used by yorick. The proper colors
should show up on 16 and 24 bit screens, and will always be OK on
color printers.

3) The Mac version of yorick doesn't have an "interrupt key" like the
control-C on unix versions, which can interrupt at an arbitrary point
in the program. Macyorick instead checks for the command-period key
when it sends a line of output to the command window and at the start
of every interpreted instruction. Interrupting macyorick works well
if you are doing a complicated interpreted calculation, but it will
not work if you have told yorick to solve a 1000x1000 matrix or some
other single operation that will take a very long time. command
period detection is turned on by default.

4) There is always a chance that yorick will cause your Mac to lock
up. Yorick checks for out of memory conditions, but it can't help if
a toolbox routine runs out of memory. The first thing to check is
thus whether the problem goes away when you increase the memory
allocation for yorick. If it is not a memory problem and you can find
a simple way to repeat the problem, I would like to know what it is
so I can try to fix it. If your Mac locks up after hours of use and
lots of number crunching, I won't be able to reproduce your problem,
so I am unlikely to be able to fix it.

5) The save window size button in the preferences dialog does not work
due to problems with the FaceIt library. I hope to fix this in a future
version.


Source Code for Mac Yorick
--------------------------
The Macintosh version of yorick was built using the FaceIt
package from FaceWare, 1310 N. Broadway, Urbana, Illinois, 61801,
[phone], [e-mail]. This package is no longer
under development, and at some future date I hope to convert to
the use of either the Symantec or Metrowerks class library.
The source code for yorick is available if you wish to build a
custom version incorporating your own compiled routines (don't
bother compiling your own routines until you are sure that an
interpreted version with array syntax is too slow). To build a
Macintosh version, you will need to get a copy of FaceIt, and
then request the Macintosh source from me.